<!DOCTYPE html>
<html prefix="og: http://ogp.me/ns#">
<head>
  <meta charset="UTF-8">
  <title>Create Your First Package</title>
  <link data-turbolinks-track="true" href="../../assets/application-b86a2086c99917c6bf2a9d74b4038381.css" media="all" rel="stylesheet" />
  <script data-turbolinks-track="true" src="../../assets/application-c3106c6fe52ccec6f26495730a478cca.js"></script>
  <meta content="authenticity_token" name="csrf-param" />
<meta content="yzXUiWH6GiCHbvbJOg7usjzA7LawyxwB+oJHEcWTOIM=" name="csrf-token" />
  <script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-3769691-35', 'atom.io');
  ga('send', 'pageview');

</script>

  <meta property="og:url" content="https://atom.io/" />
<meta property="og:site_name" content="Atom" />
<meta property="og:title" content="A hackable text editor for the 21st Century" />
<meta property="og:description" content="At GitHub, we’re building the text editor we’ve always wanted: hackable to the core, but approachable on the first day without ever touching a config file. We can’t wait to see what you build with it." />
<meta property="og:type" content="website" />
<meta property="og:author" content='https://www.facebook.com/GitHub' />
<meta property="og:image" content="http://og.github.com/atom-logo/atom-logo@1200x1200.png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="1200" />
<meta property="og:image" content="http://og.github.com/atom-mark/atom-mark@1200x630.png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />

  <meta property="twitter:card" content="summary_large_image" />
<meta property="twitter:site" content="@AtomEditor" />
<meta property="twitter:creator" content='@github' />
<meta property="twitter:title" content="Atom" />
<meta property="twitter:description" content="A hackable text editor for the 21st Century" />
<meta property="twitter:image:src" content="http://og.github.com/atom-logo/atom-logo@1200x630.png" />
<meta property="twitter:image:width" content="1200" />
<meta property="twitter:image:height" content="630" />

  <link rel="shortcut icon" href="../../favicon.ico"/>
</head>
<body>

  <div class="footer-push">
    
    

    <header class="header">
  <div class="wrapper">
    <h1 title="Atom">
      <a href="../../index.html" class="logo"></a>
    </h1>

    <ul class="navigation">
      <li><a class="" href="../../packages.html">Packages</a></li>
      <li><a class="is-selected" href="../latest/index.html">Documentation</a></li>
      <li><a href="http://blog.atom.io">Blog</a></li>
      <li><a href="../../faq.html">FAQ</a></li>
      <li><a class="" href="https://atom.io/contact">Contact</a></li>
    </ul>
  </div>
</header>


    <div class="wrapper documents content-push">
  <div class="columns">
    <div class="column main-column markdown">
        <h1>
<a name="create-your-first-package" href="your-first-package.html#create-your-first-package"></a>Create Your First Package</h1>

<p>This tutorial will guide you though creating a simple command that replaces the
selected text with <a href="http://en.wikipedia.org/wiki/ASCII_art">ascii art</a>. When you
run our new command with the word "cool" selected, it will be replaced with:</p>

<pre><code>                     ___
                    /\_ \
  ___    ___     ___\//\ \
 /'___\ / __`\  / __`\\ \ \
/\ \__//\ \L\ \/\ \L\ \\_\ \_
\ \____\ \____/\ \____//\____\
 \/____/\/___/  \/___/ \/____/
</code></pre>

<p>The final package can be viewed at
<a href="https://github.com/atom/ascii-art">https://github.com/atom/ascii-art</a>.</p>

<p>To begin, press <code>cmd-shift-P</code> to bring up the <a href="https://github.com/atom/command-palette">Command
Palette</a>. Type "generate package" and
select the "Package Generator: Generate Package" command. Now we need to name
the package. Let's call it <em>ascii-art</em>.</p>

<p>Atom will open a new window with the contents of our new <em>ascii-art</em> package
displayed in the Tree View. Because this window is opened <strong>after</strong> the package
is created, the ASCII Art package will be loaded and available in our new
window. To verify this, toggle the Command Palette (<code>cmd-shift-P</code>) and type
"ASCII Art". You'll see a new <code>ASCII Art: Toggle</code> command. When triggered, this
command displays a default message.</p>

<p>Now let's edit the package files to make our ASCII Art package do something
interesting. Since this package doesn't need any UI, we can remove all
view-related code. Start by opening up <em>lib/ascii-art.coffee</em>. Remove all view
code, so the <code>module.exports</code> section looks like this:</p>

<pre lang="coffeescript"><div class="line"><span class="source coffee"><span class="variable assignment coffee"><span class="variable assignment coffee"><span>module.exports </span><span class="keyword operator coffee"><span>=</span></span></span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="meta function coffee"><span class="entity name function coffee"><span>activat</span><span class="entity name function coffee"><span>e</span></span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="storage type function coffee"><span>-&gt;</span></span></span></div></pre>

<h2>
<a name="create-a-command" href="your-first-package.html#create-a-command"></a>Create a Command</h2>

<p>Now let's add a command. We recommend that you namespace your commands with the
package name followed by a <code>:</code>, so we'll call our command <code>ascii-art:convert</code>.
Register the command in <em>lib/ascii-art.coffee</em>:</p>

<pre lang="coffeescript"><div class="line"><span class="source coffee"><span class="variable assignment coffee"><span class="variable assignment coffee"><span>module.exports </span><span class="keyword operator coffee"><span>=</span></span></span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="meta function coffee"><span class="entity name function coffee"><span>activat</span><span class="entity name function coffee"><span>e</span></span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="storage type function coffee"><span>-&gt;</span></span></span></div><div class="line"><span class="source coffee"><span>    atom</span><span class="meta delimiter method period coffee"><span>.</span></span><span>workspaceView</span><span class="meta delimiter method period coffee"><span>.</span></span><span>command </span><span class="string quoted double coffee"><span class="punctuation definition string begin coffee"><span>"</span></span><span>ascii-art:convert</span><span class="punctuation definition string end coffee"><span>"</span></span></span><span class="meta delimiter object comma coffee"><span>, </span></span><span class="storage type function coffee"><span>=&gt;</span></span><span> </span><span class="variable other readwrite instance coffee"><span>@convert</span></span><span class="meta brace round coffee"><span>(</span><span>)</span></span></span></div><div class="line"><span class="source coffee"><span> </span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="meta function coffee"><span class="entity name function coffee"><span>conver</span><span class="entity name function coffee"><span>t</span></span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="storage type function coffee"><span>-&gt;</span></span></span></div><div class="line"><span class="source coffee"><span>    </span><span class="comment line number-sign coffee"><span class="punctuation definition comment coffee"><span>#</span></span><span> This assumes the active pane item is an editor</span></span></span></div><div class="line"><span class="source coffee"><span>    </span><span class="variable assignment coffee"><span class="variable assignment coffee"><span>editor </span><span class="keyword operator coffee"><span>=</span></span></span></span><span> atom</span><span class="meta delimiter method period coffee"><span>.</span></span><span>workspace</span><span class="meta delimiter method period coffee"><span>.</span></span><span>activePaneItem</span></span></div><div class="line"><span class="source coffee"><span>    editor</span><span class="meta delimiter method period coffee"><span>.</span></span><span>insertText</span><span class="meta brace round coffee"><span>(</span></span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>Hello, World!</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="meta brace round coffee"><span>)</span></span></span></div></pre>

<p>The <code>atom.workspaceView.command</code> method takes a command name and a callback. The
callback executes when the command is triggered. In this case, when the command
is triggered the callback will call the <code>convert</code> method and insert 'Hello,
World!'.</p>

<h2>
<a name="reload-the-package" href="your-first-package.html#reload-the-package"></a>Reload the Package</h2>

<p>Before we can trigger <code>ascii-art:convert</code>, we need to load the latest code for
our package by reloading the window. Run the command <code>window:reload</code> from the
command palette or by pressing <code>ctrl-alt-cmd-l</code>.</p>

<h2>
<a name="trigger-the-command" href="your-first-package.html#trigger-the-command"></a>Trigger the Command</h2>

<p>Now open the command panel and search for the <code>ascii-art:convert</code> command. But
it's not there! To fix this, open <em>package.json</em> and find the property called
<code>activationEvents</code>. Activation Events speed up load time by allowing Atom to
delay a package's activation until it's needed. So remove the existing command
and add <code>ascii-art:convert</code> to the <code>activationEvents</code> array:</p>

<pre lang="json"><div class="line"><span class="source json"><span class="string quoted double json"><span class="punctuation definition string begin json"><span>"</span></span><span>activationEvents</span><span class="punctuation definition string end json"><span>"</span></span></span><span>: </span><span class="meta structure array json"><span class="punctuation definition array begin json"><span>[</span></span><span class="string quoted double json"><span class="punctuation definition string begin json"><span>"</span></span><span>ascii-art:convert</span><span class="punctuation definition string end json"><span>"</span></span></span><span class="punctuation definition array end json"><span>]</span></span></span><span>,</span></span></div></pre>

<p>First, reload the window by running the command <code>window:reload</code>. Now when you
run the <code>ascii-art:convert</code> command it will output 'Hello, World!'</p>

<h2>
<a name="add-a-key-binding" href="your-first-package.html#add-a-key-binding"></a>Add a Key Binding</h2>

<p>Now let's add a key binding to trigger the <code>ascii-art:convert</code> command. Open
<em>keymaps/ascii-art.cson</em> and add a key binding linking <code>ctrl-alt-a</code> to the
<code>ascii-art:convert</code> command. You can delete the pre-existing key binding since
you don't need it anymore. When finished, the file will look like this:</p>

<pre lang="coffeescript"><div class="line"><span class="source coffee"><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>.editor</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>cmd-alt-a</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>ascii-art:convert</span><span class="punctuation definition string end coffee"><span>'</span></span></span></span></div></pre>

<p>Notice <code>.editor</code> on the first line. Just like CSS, keymap selectors <em>scope</em> key
bindings so they only apply to specific elements. In this case, our binding is
only active for elements matching the <code>.editor</code> selector. If the Tree View has
focus, pressing <code>cmd-alt-a</code> won't trigger the <code>ascii-art:convert</code> command. But
if the editor has focus, the <code>ascii-art:convert</code> method <em>will</em> be triggered.
More information on key bindings can be found in the
<a href="advanced/keymaps.html">keymaps</a> documentation.</p>

<p>Now reload the window and verify that the key binding works! You can also verify
that it <strong>doesn't</strong> work when the Tree View is focused.</p>

<h2>
<a name="add-the-ascii-art" href="your-first-package.html#add-the-ascii-art"></a>Add the ASCII Art</h2>

<p>Now we need to convert the selected text to ASCII art. To do this we will use
the <a href="https://npmjs.org/package/figlet">figlet</a> <a href="http://nodejs.org/">node</a> module
from <a href="https://npmjs.org/">npm</a>. Open <em>package.json</em> and add the latest version of
figlet to the dependencies:</p>

<pre lang="json"><div class="line"><span class="source json"><span class="string quoted double json"><span class="punctuation definition string begin json"><span>"</span></span><span>dependencies</span><span class="punctuation definition string end json"><span>"</span></span></span><span>: </span><span class="meta structure dictionary json"><span class="punctuation definition dictionary begin json"><span>{</span></span></span></span></div><div class="line"><span class="source json"><span class="meta structure dictionary json"><span>   </span><span class="string quoted double json"><span class="punctuation definition string begin json"><span>"</span></span><span>figlet</span><span class="punctuation definition string end json"><span>"</span></span></span><span class="meta structure dictionary value json"><span class="punctuation separator dictionary key-value json"><span>:</span></span><span> </span><span class="string quoted double json"><span class="punctuation definition string begin json"><span>"</span></span><span>1.0.8</span><span class="punctuation definition string end json"><span>"</span></span></span></span></span></span></div><div class="line"><span class="source json"><span class="meta structure dictionary json"><span class="punctuation definition dictionary end json"><span>}</span></span></span></span></div></pre>

<p>After saving the file, run the command 'update-package-dependencies:update' from
the Command Palette. This will install the package's node module dependencies,
only figlet in this case. You will need to run
'update-package-dependencies:update' whenever you update the dependencies field
in your <em>package.json</em> file.</p>

<p>Now require the figlet node module in <em>lib/ascii-art.coffee</em> and instead of
inserting 'Hello, World!' convert the selected text to ASCII art.</p>

<pre lang="coffeescript"><div class="line"><span class="source coffee"><span class="meta function coffee"><span class="entity name function coffee"><span>conver</span><span class="entity name function coffee"><span>t</span></span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="storage type function coffee"><span>-&gt;</span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="comment line number-sign coffee"><span class="punctuation definition comment coffee"><span>#</span></span><span> This assumes the active pane item is an editor</span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="variable assignment coffee"><span class="variable assignment coffee"><span>editor </span><span class="keyword operator coffee"><span>=</span></span></span></span><span> atom</span><span class="meta delimiter method period coffee"><span>.</span></span><span>workspace</span><span class="meta delimiter method period coffee"><span>.</span></span><span>activePaneItem</span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="variable assignment coffee"><span class="variable assignment coffee"><span>selection </span><span class="keyword operator coffee"><span>=</span></span></span></span><span> editor</span><span class="meta delimiter method period coffee"><span>.</span></span><span>getSelection</span><span class="meta brace round coffee"><span>(</span><span>)</span></span></span></div><div class="line"><span class="source coffee"><span> </span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="variable assignment coffee"><span class="variable assignment coffee"><span>figlet </span><span class="keyword operator coffee"><span>=</span></span></span></span><span> </span><span class="support function coffee"><span>require</span></span><span> </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>figlet</span><span class="punctuation definition string end coffee"><span>'</span></span></span></span></div><div class="line"><span class="source coffee"><span>  figlet selection</span><span class="meta delimiter method period coffee"><span>.</span></span><span>getText</span><span class="meta brace round coffee"><span>(</span><span>)</span></span><span class="meta delimiter object comma coffee"><span>, </span></span><span class="meta brace curly coffee"><span>{</span></span><span class="variable assignment coffee"><span class="variable assignment coffee"><span>font</span><span class="punctuation separator key-value"><span>:</span></span></span></span><span> </span><span class="string quoted double coffee"><span class="punctuation definition string begin coffee"><span>"</span></span><span>Larry 3D 2</span><span class="punctuation definition string end coffee"><span>"</span></span></span><span class="meta brace curly coffee"><span>}</span></span><span class="meta delimiter object comma coffee"><span>, </span></span><span class="meta inline function coffee"><span class="variable parameter function coffee"><span>(error, asciiArt)</span></span><span> </span><span class="storage type function coffee"><span>-&gt;</span></span></span></span></div><div class="line"><span class="source coffee"><span>    </span><span class="keyword control coffee"><span>if</span></span><span> error</span></span></div><div class="line"><span class="source coffee"><span>      </span><span class="entity name type object coffee"><span>console</span></span><span class="meta delimiter method period coffee"><span>.</span></span><span class="support function console coffee"><span>error</span></span><span class="meta brace round coffee"><span>(</span></span><span>error</span><span class="meta brace round coffee"><span>)</span></span></span></div><div class="line"><span class="source coffee"><span>    </span><span class="keyword control coffee"><span>else</span></span></span></div><div class="line"><span class="source coffee"><span>      selection</span><span class="meta delimiter method period coffee"><span>.</span></span><span>insertText</span><span class="meta brace round coffee"><span>(</span></span><span class="string quoted double coffee"><span class="punctuation definition string begin coffee"><span>"</span></span><span class="constant character escape coffee"><span>\n</span></span><span class="source coffee embedded source"><span class="punctuation section embedded coffee"><span>#{</span></span><span>asciiArt</span><span class="punctuation section embedded coffee"><span>}</span></span></span><span class="constant character escape coffee"><span>\n</span></span><span class="punctuation definition string end coffee"><span>"</span></span></span><span class="meta brace round coffee"><span>)</span></span></span></div></pre>

<p>Select some text in an editor window and hit <code>cmd-alt-a</code>. <img title=":tada:" alt=":tada:" src="https://a248.e.akamai.net/assets.github.com/images/icons/emoji/tada.png" height="20" width="20" align="absmiddle"> You're now an
ASCII art professional!</p>

<h2>
<a name="further-reading" href="your-first-package.html#further-reading"></a>Further reading</h2>

<ul>
<li><p><a href="http://guides.github.com/overviews/desktop">Getting your project on GitHub guide</a></p></li>
<li><p><a href="creating-a-package.html">Creating a package guide</a> for more information
on the mechanics of packages</p></li>
<li><p><a href="https://atom.io/docs/v0.61.0/publish-a-package">Publishing a package guide</a> for more information
on publishing your package to <a href="../../index.html">atom.io</a></p></li>
</ul>
    </div>
    <div class="column sidebar documents-toc">
      <select class="js-doc-version-switcher version-switcher">
  <option value="v0.69.0">v0.69.0</option>
<option value="v0.68.0">v0.68.0</option>
<option value="v0.67.0">v0.67.0</option>
<option value="v0.66.0">v0.66.0</option>
<option value="v0.65.0">v0.65.0</option>
<option value="v0.64.0">v0.64.0</option>
<option value="v0.63.0">v0.63.0</option>
<option value="v0.62.0">v0.62.0</option>
<option selected="selected" value="v0.61.0">v0.61.0</option>
<option value="v0.60.0">v0.60.0</option>
<option value="v0.59.0">v0.59.0</option>
<option value="v0.58.0">v0.58.0</option>
<option value="v0.57.0">v0.57.0</option>
<option value="v0.56.0">v0.56.0</option>
<option value="v0.55.0">v0.55.0</option>
<option value="v0.54.0">v0.54.0</option>
<option value="v0.53.0">v0.53.0</option>
<option value="v0.51.0">v0.51.0</option>
<option value="v0.50.0">v0.50.0</option>
<option value="v0.49.0">v0.49.0</option>
<option value="v0.48.0">v0.48.0</option>
<option value="v0.47.0">v0.47.0</option>
<option value="v0.46.0">v0.46.0</option>
<option value="v0.45.0">v0.45.0</option>
<option value="v0.44.0">v0.44.0</option>
<option value="v0.41.0">v0.41.0</option>
<option value="v0.40.0">v0.40.0</option>
<option value="0.52.0">0.52.0</option>
</select>


      <ul class="navigation">
        <li><a href="" class="is-selected">Documentation</a></li>
        <li><a href="../api/v0.61.0/api/index.html">API</a></li>
      </ul>

      <hr />

      <form accept-charset="UTF-8" action="/docs/v0.61.0/search" method="get"><div style="margin:0;padding:0;display:inline"><input name="utf8" type="hidden" value="&#x2713;" /></div>
        <input class="sidebar-search-field" id="q" name="q" placeholder="Search documentation" type="text" value="" />
</form>
      <h2>
<a name="guides" href="your-first-package.html#guides"></a>Guides</h2>

<ul>
<li><a href="getting-started.html">Getting Started</a></li>
<li><a href="customizing-atom.html">Customizing Atom</a></li>
<li><a href="creating-a-package.html">Creating a Package</a></li>
<li><a href="creating-a-theme.html">Creating a Theme</a></li>
<li><a href="publishing-a-package.html">Publishing a Package</a></li>
<li><a href="converting-a-text-mate-bundle.html">Converting a TextMate Bundle</a></li>
<li><a href="converting-a-text-mate-theme.html">Converting a TextMate Theme</a></li>
<li><a href="contributing.html">Contributing</a></li>
</ul><h3>
<a name="advanced-topics" href="your-first-package.html#advanced-topics"></a>Advanced Topics</h3>

<ul>
<li><a href="advanced/configuration.html">Configuration</a></li>
<li><a href="advanced/keymaps.html">Keymaps</a></li>
<li><a href="advanced/serialization.html">Serialization</a></li>
<li><a href="advanced/view-system.html">View System</a></li>
</ul>
    </div>
  </div>
</div>


    <div class="footer-pad"></div>
  </div>

  <footer>
  <div class="footer">
    <div class="wrapper">
      <ul class="footer-left">
        <li><a href="../../terms.html">Terms of Use</a></li>
          <li><a href="https://atom.io/login">Sign in</a></li>
      </ul>

      <div class="footer-right">
        <a href="https://github.com"><span class="octicon octicon-code"></span> with <span class="octicon octicon-heart"></span> by <span class="octicon octicon-logo-github"></span></a>
      </div>
    </div>
  </div>
</footer>

</body>
</html>
